home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / ada / gwuada_5.zip / adaed / nyudemos / pager2.doc < prev    next >
Text File  |  1992-09-01  |  15KB  |  478 lines
  1.                                      PAGER2
  2.  
  3.                                 by Richard Conn
  4.  
  5.                   PAGER2 is   a  tool  for  creating  paged  files,
  6.              extracting  the component files from a paged file, and
  7.              scanning  paged  files,   where   a  paged  file  is a
  8.              file  composed  of  one  or  more  files  prefixed  by
  9.              banners.    PAGER2   is  based  in  concept   on   the
  10.              UNPAGE   tool submitted to the Ada Software Repository
  11.              on SIMTEL20 by Mitre Corporation.  
  12.  
  13.                   Paged files   are   convenient   mechanisms   for
  14.              storing  related   files.   They   reduce   cluttering
  15.              in   the  directories  and  simplify the file transfer
  16.              process  by requiring  the  user  to transfer only one
  17.              file  in  order  to  obtain  all  files pertinent to a
  18.              particular  project  or  tool.   Additionally,   paged
  19.              files   are  text  files  which  can  be  handled more
  20.              readily  than  the 8-bit binary images associated with
  21.              other   file   grouping   mechanisms  (see   the  file
  22.              OILBR.DOC     in   the   directory   PD2:<ADA.GENERAL>
  23.              in   the   Ada  Software Repository).  Paged files may
  24.              be  manipulated  by  a  text  editor  if necessary.  
  25.  
  26.                   For these   reasons,   paged   files   have  been
  27.              adopted   as   a   standard  for  file  storage in the
  28.              Ada  Software Repository.  The file type of SRC (as in
  29.              MYFILE.SRC) indicates that a file is paged.  
  30.  
  31.  
  32.  
  33.  
  34.           1.  PAGED FILE FORMAT 
  35.  
  36.                A paged  file  is  a file composed of one or more files
  37.           prefixed  by banners of the form: 
  38.  
  39.                           ::::::::::
  40.                           filename
  41.                           ::::::::::
  42.           or
  43.                           --::::::::::
  44.                           --filename
  45.                           --::::::::::
  46.  
  47.                The first   banner   conforms   to  the  PAGE  standard
  48.           employed  on  UNIX.  The  second  banner is an adaptation of
  49.           the  first  form  which  resembles Ada comments.  The second
  50.           banner  is  convenient   when   the   paged   file  contains
  51.           several   files   associated  with  a particular Ada program
  52.           and  they  are  placed  in  the  paged  file  in compilation
  53.  
  54.  
  55.           Richard Conn                                          Page 1
  56.  
  57.  
  58.                                      PAGER2
  59.  
  60.  
  61.           order.   The  resulting  paged  file  may  then  be compiled
  62.           without being disassembled first.  
  63.  
  64.  
  65.  
  66.  
  67.           2.  PAGER2 COMMANDS 
  68.  
  69.                PAGER2 responds to the following commands: 
  70.  
  71.                 1.  PAGE or P - create a paged file 
  72.  
  73.                 2.  UNPAGE  or U - extract the components of a
  74.                   paged file into their separate files 
  75.  
  76.                 3.  LIST  or  L  -  list components of a paged
  77.                   file to the screen 
  78.  
  79.                 4.  INCLUDE  or I - list components of a paged
  80.                   file into an include file 
  81.  
  82.                 5.  HELP or H - print a command summary 
  83.  
  84.                 6.  EXIT or X - exit PAGER2 
  85.  
  86.                The case  used  to  enter  these  command  verbs is not
  87.           significant.    The  case  used  to  enter  the  file  names
  88.           referenced  as arguments to the command verbs is significant
  89.           if  the  host  operating  system  distinguishes case in file
  90.           names, as does UNIX (but not MSDOS).  
  91.  
  92.  
  93.           2.1.  PAGE Command 
  94.  
  95.                The PAGE  function  is  used  to  created a paged  file
  96.           from   one  or more component files.  The syntax of the PAGE
  97.           command is: 
  98.  
  99.                PAGE [filename | @include_filename]+ paged_file_name
  100.  
  101.                Two or  more file names may be specified after the PAGE
  102.           verb.   The  last file name is the name of the paged file to
  103.           be  created.  The other file names are the names of files to
  104.           be  placed into the paged file or the names of include files
  105.           from  which  the  names of files to be placed into the paged
  106.           file are to be extracted.  
  107.  
  108.                If the  user prefixes the name of a component file with
  109.           an   atsign  character  (@), the indicated file is processed
  110.           as  an  include  file.   An  include  file  is  a file which
  111.           contains   the   names  of  zero  or  more component  files,
  112.           one   name   per  line  starting in the first column.  Other
  113.  
  114.  
  115.           Richard Conn                                          Page 2
  116.  
  117.  
  118.                                      PAGER2
  119.  
  120.  
  121.           include  files  may   be   referenced   within   an  include
  122.           file    by   prefixing   their   names   with   the   atsign
  123.           character.   Comments  may  be placed within an include file
  124.           by  placing  two  dashes  in  the   first   two columns of a
  125.           line.  The following is an example of an include file: 
  126.  
  127.                    Example                      Comments
  128.                    =======                      ========
  129.           --
  130.           -- This is an include file for        Comment at the beginning
  131.           --  my favorite tool
  132.           --
  133.                                                 Blank lines are allowed
  134.           --
  135.           -- The following include file
  136.           --  contains the names of the         Another comment
  137.           --  Ada source files in compilation
  138.           --  order
  139.           --
  140.           @mytool.cmp
  141.           --
  142.           -- The following are the documentation
  143.           --  files
  144.           --
  145.           mytool.ref
  146.           mytool.doc
  147.           mytool.idx
  148.  
  149.                A single  letter  "P"  may be used rather than the full
  150.           "PAGE"  verb.   An  example  of  the  execution  of the PAGE
  151.           command is: 
  152.  
  153.           PAGER2> page
  154.            PAGE Command requires the name of the paged file and include file
  155.              Syntax: page [@include_file_name|file_name]+ paged_file_name
  156.           PAGER2> p @demo.inc demo.src
  157.            Adding demo.inc -- 8 Lines
  158.            Adding demo1.txt -- 1 Lines
  159.            Adding demo2.txt -- 1 Lines
  160.  
  161.  
  162.           2.2.  UNPAGE Command 
  163.  
  164.                The UNPAGE  function  extracts  the   components   from
  165.           the   indicated  paged   file,  leaving  the  original paged
  166.           file intact.  The syntax of UNPAGE is: 
  167.  
  168.               UNPAGE paged_filename
  169.  
  170.                The single  letter "U" may be used rather than the full
  171.           "UNPAGE"  verb.   An  example of the execution of the UNPAGE
  172.           command is: 
  173.  
  174.  
  175.           Richard Conn                                          Page 3
  176.  
  177.  
  178.                                      PAGER2
  179.  
  180.  
  181.           PAGER2> unpage
  182.            UNPAGE Command requires the name of a paged file
  183.              Syntax: unpage paged_file_name
  184.           PAGER2> u demo.src
  185.            Extracting demo.inc -- 8 Lines
  186.            Extracting demo1.txt -- 1 Lines
  187.            Extracting demo2.txt -- 1 Lines
  188.  
  189.  
  190.           2.3.  LIST Command 
  191.  
  192.                The LIST  function  is  used  to  create  a  text  file
  193.           containing   the  names   of   the  component files within a
  194.           paged file.  The syntax of the LIST command is: 
  195.  
  196.                LIST paged_file_name
  197.  
  198.                The single  letter "L" may be used rather than the full
  199.           "LIST"  verb.   An  example  of  the  execution  of the LIST
  200.           command is: 
  201.  
  202.           PAGER2> list
  203.            LIST Command requires the name of a paged file
  204.              Syntax: list paged_file_name
  205.           PAGER2> list demo.src
  206.            demo.inc -- 8 Lines
  207.            demo1.txt -- 1 Lines
  208.            demo2.txt -- 1 Lines
  209.  
  210.  
  211.           2.4.  INCLUDE Command 
  212.  
  213.                The INCLUDE  command  performs the same function of the
  214.           LIST  command, but it places the output into an includ